BooBoo logo

Jump to:

BooBoo Core Functionality

The following describe the core functions of BooBoo. All of this can be used from the CLI version as well as the game engine.

Many or most operators/functions support multiple parameters, e.g. (+ 1 2 3 4 5) is 15.

Sections:

Core Functions

var

	declare a variable or variables
	e.g. var x y z

const

	Declare one or more constants. You must set a value for every constant.
	e.g. const var1 val1 var2 val2

reset

	load a different BooBoo script
	This is seamless and more or less instant. If you start drawing
	the same thing in the next script, the player may not know the
	script changed. It's useful for different game modes, menus,
	high scores etc... state information can be passed between scripts
	using the configuration API.
	e.g. reset "next_slide.boo"

exit

	Exit the app with a return code to the environment
	e.g. exit 0

return

	Return a value from a function
	e.g. return 1
	or just return if the function doesn't return a value

include

	Include a BooBoo file at this point in the code
	e.g. include "my_functions.inc"

:

	Define a label
	e.g. :jump_here

;

	Define a comment
	e.g. = x 1 ; assign 1 to x

/* */

	A multiline comment
	e.g. call foo bar /* foo bar */ baz

" "

	a string
	e.g. = name "Pelvis Johnson"

function

	define a function
	References can be defined by prefixing a parameter name by a tilde (~)
	e.g. function foo param1 param2 ~param3 { ... }

(typeof)

	Returns a string respresentation of the type of the second parameter
	e.g. = type_string (typeof my_var)

()

	an expression
	e.g. (+ x (* y (* z w 2))) in C would be x+(y*(z*w*2))
	Supported operators are: + - * / % && || > < >= <= == != ! | ^ & << >>
	The boolean operators return 1 or 0
	Your own functions can be supplied as operators

[]

	Vector/map indexing operator
	e.g. = x [v [m "key"]] in C++ would be x = v[m["key"]]
	Can be used anywhere a variable is expected.
	You can use multiple indexes
	e.g. [v 3 2 1 0] is like v[3][2][1][0] in C.

#

	Start a hexadecimal number
	e.g. #FF is equivalent to 255

' '

	A character. The character between quotes is turned to a
	number between 0 and 255.
	e.g. print "%(c)\n" 'a'

~

	A reference. Function parameters preceded by a ~ can be modified
	by a function
	e.g. function foo a b ~c d ~e { ... } ; c and e can be modified

@

	The address operator
	e.g. = my_pointer (@ my_var)
	or
	call foo (@ bar) ; where foo is expecting a pointer

`

	Dereference operator. This is used to get/set the value pointed
	to by a pointer
	e.g. = p (@ some_num)
	e.g. = `p 10 ; some_num is now 10

(toptr)

	You can do some basic "reflection" using toptr to get a pointer
	to the variable with the name in a string.
	e.g. var foo
	e.g. = number 10
	e.g. var bar
	e.g. = bar "foo"
	e.g. = `(toptr bar) 1000 ; foo is now 1000
	You can use this to script BooBoo with function names/etc in a text file.
	Returns NULL if the variable isn't found

=

	assign
	e.g. = x 1

(number)

	Cast to a number
	e.g. = n (number str)

(string)

	Cast to a string
	e.g. = str (string num)

(vector)

	Cast to a vector
	e.g. var foo
	e.g. = foo (vector foo)

(map)

	Cast to a map
	e.g. var foo
	e.g. = foo (map foo)

(function)

	Cast to a function
	e.g. var foo
	e.g. = foo (function foo)

(label)

	Cast to a label
	e.g. var foo
	e.g. = foo (label foo)

(pointer)

	Cast to a pointer
	e.g. var foo
	e.g. = foo (pointer foo)

Flow Control

goto

	jump to a label
	e.g. goto next_loop

?

	Comparison
	e.g. ? x 1
	You can also evaluate an expression
	? 1 (&& (> a b) (< x y)) je true jne false

je

	Jumps like this one are based on the last comparison. If it was equal,
	this will jump, if not, it won't
	e.g. je process_x_equals_1

jne

	Jump if not equal
	e.g. jne process_x_not_1

jl

	Jump if less
	e.g. jl my_label

jle

	Jump if less or equal
	e.g. jle my_label

jg

	Jump if greater
	e.g. jg my_label

jge

	Jump if greater or equal
	e.g. jge my_label

call

	Call a function that doesn't return anything
	e.g. call my_func param1 param2 param2

call_result

	Call a function that returns a value
	e.g. call_result result my_func param1 param2

if

	compare and jump
	e.g. if (expr1) the_if (expr2) elseif1 (expr3) elseif2 the_else
		; expr1 true code
	:the_if
		; expr2 true code
	:elseif1
		; expr3 true code
	:elseif2
		; else code
	:the_else

	the_if elseif1 elseif2 and the_else are labels that are the bottom of
	their code blocks. The else block is optional. Labels need to be in
	order of appearance in the if statement or behaviour is undefined.

for

	A for loop
	e.g. for i start (expression) increment end_label
		; your loop code here
	:end_label
	i is initialised to "start" then gets incremented
	by increment each loop until expression returns
	FALSE.
	break and continue work in loops

while

	A while loop
	break and continue work in loops
	e.g. while (< i 10) loop /* code here */ :loop

do_while

	A do/while loop
	The expression is first evaluated after the body is run, despite
	it being at the top...
	break and continue work in loops
	e.g. do_while (< i 10) loop /* code here */ :loop

String Functions

(string_format)

	format strings with replacements
	e.g. = dest (string_format "I'm % years old" age)
	printf-equivalent formating options are available with %(...) for
	example %(3.16g)

(string_char_at)

	Get the value of character at index in a string
	This function is UTF8 compliant
	e.g. = dest (string_char_at str index)

string_set_char_at

	Set character at position in string
	This is UTF8 compliant
	e.g. string_set_char_at s pos value

(string_length)

	Get the length of a string
	This function is UTF8 compliant
	e.g. = dest (string_length str)

(string_from_number)

	Turns the ascii value into a one character length string
	This function is UTF8 compliant
	e.g. = str (string_from_number 97) ; creates "a"

(string_substr)

	Create a substring of a string
	e.g. = s (string_substr s start end)
	End is optional, if not specified it will cut from start till the
	end of the string.
	This is UTF8 compliant

(string_trim)

	Trim leading and trailing whitespace from a string
	The trim functions are UTF8 compliant
	e.g. = s (string_trim s)

(string_ltrim)

	Trim leading whitespace from a string
	The trim functions are UTF8 compliant
	e.g. = s (string_trim s)

(string_rtrim)

	Trim trailing whitespace from a string
	The trim functions are UTF8 compliant
	e.g. = s (string_trim s)

(string_uppercase)

	Make a string uppercase
	e.g. = s (string_uppercase s)

(string_lowercase)

	Make a string lowercase
	e.g. = s (string_lowercase s)

(string_replace)

	regex replacement
	Default is case sensitive
	e.g. = str (string_replace str regex replacement ^ ignore_case)

(string_match)

	Extract sub-strings from a string
	Default is case sensitive
	e.g. = out_vector (string_match str regex ^ ignorecase)

(string_matches)

	Check if a string matches a regex
	Default is case sensitive
	e.g. = yesno (string_matches str regex ^ ignorecase)

Math Functions

(fmod)

	floating point modulus
	e.g. = x (fmod x 1.5)

(sin)

	trigonometry functions
	e.g. = n (sin n)

(cos)

	trigonometry functions
	e.g. = n (cos n)

(tan)

	trigonometry functions
	e.g. = n (tan n)

(asin)

	trigonometry functions
	e.g. = n (asin n)

(acos)

	trigonometry functions
	e.g. = n (acos n)

(atan)

	trigonometry functions
	e.g. = n (atan n)

(atan2)

	trigonometry functions
	e.g. = n (atan2 y x)

(abs)

	absolute value
	e.g. = n (abs value)

(pow)

	exponentiation
	e.g. = n (pow x 2)

(sqrt)

	square root
	e.g. = n (sqrt x)

(hypot)

	Calculate hypotenuse of a and b
	e.g. = n (hypot a b)

(floor)

	Drop the fractional part of a number
	e.g. = n (floor x)

(ceil)

	Round to the next highest integer
	e.g. = n (ceil x)

(neg)

	Invert the sign of a number
	e.g. = n (neg x)

(sign)

	Returns the sign of a number
	e.g. = n (sign x)

(exp)

	Calculate the value of e
	e.g. = n (exp x)

(log)

	Logarithm function
	e.g. = n (log x)

(log10)

	Base 10 logarithm
	e.g. = n (log10 x)

(min)

	Get the minimum number in a list of values
	e.g. = n (min a b c d e f g)

(max)

	Get the max number in a list of values
	e.g. = n (max a b)

Vector and matrix math

	Some vector and matrix math is available through expression
	operators. Supported are: mul, identity, scale, rotate,
	translate, length, dot, angle, cross, normalize, add, sub,
	inverse, transpose, frustum, perspective, ortho
	Most of these behave as you'd expect. identity takes 1 argument,
	the size of the matrix. scale, rotate and translate produce
	transformation matrices to be multiplied by another matrix
	(scale and translate take 3 parameters, rotate takes 4.)

Vector Functions

vector_add

	push a value onto a vector
	e.g. vector_add v 0

(vector_size)

	get the number of elements in a vector
	e.g. = size (vector_size vec)

vector_insert

	insert a value in any position in a vector
	e.g. vector_insert v index value

vector_erase

	remove from a vector
	e.g. vector_erase v index

vector_clear

	empty a vector or vectors
	e.g. vector_clear v1 v2

vector_reserve

	Allocate space for at least n elements to avoid reallocations
	e.g. vector_reserve v n

sort

	Sort a vector
	Takes a vector and a comparator function.
	The comparator function should take 2 arguments and return
	TRUE if the first is less than the second, otherwise FALSE.
	e.g. sort vec y_sort

unique

	Remove all non-unique elements from a sorted vector
	e.g. unique vec

explode

	Assign sequential vector elements to variables
	e.g. var v
	e.g. vector_init v 1 2 3 4 5
	e.g. var a b c
	e.g. explode v a b c ; 1 2 3 in a b c

Map Functions

map_erase

	erase a key/value pair from a map
	e.g. map_erase m "key"

map_clear

	clear a map or maps
	e.g. map_clear m

(map_keys)

	Get the names of the keys from a map into a vector of strings
	e.g. = v (map_keys m)

File Functions

(file_open)

	open a file, mode can be either "a" "r" or "w"
	"a" means append, "w" means write (overwrite)
	and "r" means read mode.
	e.g. var f
	e.g. = f (file_open "out.txt "w")
	f will be -1 on failure

(file_open_cpa)

	open a file from CPA. These are read only. All file read operations are supported.
	e.g. = f (file_open_cpa "foo.txt")

file_close

	You should always close files you open with this
	e.g. file_close f

(file_read)

	Read a word from a file
	Returns empty string on eof
	e.g. = s (file_read f)

(file_read_line)

	Read a line from a file
	Returns empty string (no newline) on eof
	e.g. = s (file_read_line f)

(file_read_byte)

	Read a byte from a file. Returns a negative number on eof
	e.g. = n (file_read_byte f)

file_write_byte

	Write a byte to a file
	e.g. file_write_byte f 255

file_write

	Write a word to a file
	e.g. file_write f "turkey"

file_print

	Print to a file. Behaves exactly like print but takes a file
	e.g. file_print f "%(20s)%(20s)%(20s)" x y z

(file_tell)

	Return the current file offset
	e.g. = o (file_tell f)

file_seek

	Seek within file. Uses SEEK_* constants.
	e.g. file_seek f 0 SEEK_END

Configuration Functions

(cfg_load)

	load a config file
	These files are saved in Saved Games\BooBoo along with
	every BooBoo app, so you should use a domain name or
	unique name
	e.g. = cfg (cfg_load "com.nooskewl.example")

(cfg_save)

	save a config file
	e.g. = success (cfg_save cfg "com.nooskewl.example")

(cfg_get_number)

	read a number from config.
	e.g. = dest (cfg_get_number cfg "x")

(cfg_get_string)

	read a string from config
	e.g. = dest (cfg_get_string cfg "name")

cfg_set_number

	set a value to be saved in a config file
	e.g. cfg_set_number cfg "x" 1

cfg_set_string

	set a string value in a config file
	e.g. cfg_set_string cfg "name" "Trent"

(cfg_exists)

	check if a value exists in a config file
	e.g. = exists (cfg_exists cfg "x")

cfg_erase

	Erase a value in a config file
	e.g. cfg_erase cfg "example"

cfg_destroy

	Free a configuration object
	e.g. cfg_destroy cfg

JSON Functions

You can dig down into the file by separating keys with ">"

"[0]" "[1]" etc can be used to access arrays.

You can use NULL to access the shim5.json object.

(json_load)

	Load a JSON file. This loads from CPA unless lffs is TRUE.
	e.g. = j (json_load "file.json" ^ lffs)
	Returns -1 on fail

(json_create)

	Create a blank JSON file. Takes a boolean that creates the root
	as either an array (TRUE) or hash (FALSE)
	e.g. = j (json_create FALSE)
	Returns -1 on fail

(json_exists)

	Check if a key exists in a JSON object
	e.g. = yesno (json_exists json "foo>bar>baz")

(json_typeof)

	Return a string representation of JSON key type
	e.g. = val (json_typeof json "foo>bar>baz")

(json_size)

	Return the number of children of a JSON key
	e.g. = n (json_size json "foo>bar>baz")

(json_get_string)

	Read a string from JSON
	e.g. = s (json_get_string json "settings>profile>name")

(json_get_number)

	Read a number from JSON
	e.g. = n (json_get_number json "settings>mouse>sensitivity")

(json_get_bool)

	Read a boolean from JSON
	e.g. = n (json_get_boolean json "settings>gfx>crt_filter")

json_set_string

	Set a string in a JSON object
	e.g. json_set_string json "foo>bar>baz" "TURNIPS"

json_set_number

	Set a number in a JSON object
	e.g. json_set_number json "foo>bar>baz" 762.4

json_set_bool

	Set a boolean in a JSON object
	e.g. json_set_bool json "foo>bar>baz" TRUE

json_add_array

	Add an array element to a json object.
	e.g. json_add_array json "foo>bar>baz"

json_add_hash

	Add a hash element to a json object.
	e.g. json_add_array json "foo>bar>baz"

json_remove

	Remove a child from JSON tree
	e.g. json_remove json "foo>bar>baz"

(json_save)

	Save a json object to json file
	e.g. = succeeded (json_save json "foo.json")

json_destroy

	Free a JSON object
	e.g. json_destroy json

json_register_number

	Register a number with DevSettings
	You can access devsettings by running with +debug and pressing F9
	A "game>" prefix is added automatically. The optional callback is
	called with the key's name when the value is changed in devsettings
	e.g. json_register_number n "foo>baz" readonly ^ callback

json_register_string

	Register a string with DevSettings
	You can access devsettings by running with +debug and pressing F9
	A "game>" prefix is added automatically. The optional callback is
	called with the key's name when the value is changed in devsettings
	e.g. json_register_string s "foo>baz" readonly ^ callback

CPA Functions

CPAs are extra datafiles with the same structure as data.cpa.

(cpa_load)

	Load a CPA datafile.
	e.g. = cpa (cpa_load "file.cpa" ^ lffs)
	Returns -1 on fail

cpa_set

	Change the default CPA file. All functions that load from data/data.cpa will
	now load from this CPA, until cpa_set_default is called.
	e.g. cpa_set cpa

cpa_set_default

	Restore the default CPA datafile
	e.g. cpa_set_default

(file_list)

	Get a list of files in the data/ directory or data.cpa (just the current
	CPA in the CLI version)
	e.g. = vec (file_list)

cpa_destroy

	Free a CPA datafile
	e.g. cpa_destroy cpa

Audio Functions

Supported sample types are wav, ogg and flac.

Since there is no engine loop in the CLI version, audio callbacks are called between statements in that version.

The _load functions load from CPA by default, so in CLI, you'll want to set TRUE for lffs (load from filesystem) unless you have set a CPA with cpa_set.

(get_audio_properties)

	Get device frequency/channels
	e.g. explode (get_audio_properties) freq channels

(mml_create)

	create an MML from a string. See the Music documentation section.
	e.g. = dest (mml_create "A @TYPE3 abcdefg")
	; this plays a b c d e f g 16th notes with a sine wave generator
	Returns -1 on fail

(mml_load)

	load an MML from file
	e.g. = dest (mml_load "sfx/blast.mml" ^ lffs)
	Returns -1 on fail

(mml_play)

	play a sound. Returns an instance that can be adjusted
	e.g. = inst (mml_play blast ^ volume loop pan callback)

mml_stop

	stop an MML instance
	e.g. mml_stop inst

mml_set_volume

	Set the volume of an MML instance
	Set a specific track or -1 the default is all tracks
	e.g. mml_set_volume inst 0.5 ^ track

mml_set_pan

	Set the pan of an MML instance
	-1: left 0: center 1: right
	Set a specific track or -1 the default is all tracks
	e.g. mml_set_pan inst -1 ^ track

mml_set_tempo

	Set the tempo of all tracks of an MML. After this is called,
	further 't's (in MML syntax) will be ignored
	Set a specific track or -1 the default is all tracks
	e.g. mml_set_tempo inst 120 ^ track

(mml_get_volume)

	Get the volume of a track. Track is mandatory. If you're just setting them all
	at once, just use track 0 here.
	= vol (mml_get_volume inst track)

(mml_get_pan)

	Get the pan of a track. Track is mandatory. If you're just setting them all
	at once, just use track 0 here.
	= pan (mml_get_pan inst track)

(mml_get_tempo)

	Get the tempo of a track. Track is mandatory. If you're just setting them all
	at once, just use track 0 here.
	= tempo (mml_get_tempo inst track)

(mml_num_tracks)

	Get the number of tracks in an MML file
	e.g. = tracks (mml_num_tracks mml)

mml_destroy

	Free an MML
	e.g. mml_destroy mml

(sample_load)

	load a sample
	e.g. = s (sample_load "example.wav" ^ lffs)
	Returns -1 on fail

(sample_create)

	Create a sample from vector of sample data
	The vector contains S16LE (-32767 to 32768) interlaced for each channel
	e.g. = samp (sample_create vec freq channels)

sample_play

	play a sample. Returns a sample instance that can be adjusted
	An optional duration can be used otherwise it will playback
	at normal speed
	e.g. = inst (sample_play s ^ volume loop pan playtime_millis callback)

sample_stop

	Stop a sample instance
	e.g. sample_stop inst

sample_set_volume

	Set the volume of a playing sample instance
	e.g. sample_set_volume inst 0.5

sample_set_pan

	Set the pan of an MML instance
	-1: left 0: center 1: right
	e.g. sample_set_pan inst -1

(sample_length)

	Returns the length in milliseconds of a sample
	e.g. = len (sample_length samp)

(sample_elapsed)

	Get elapsed time of sample in milliseconds
	e.g. = millis (sample_elapsed samp)

(sample_get_volume)

	Get the volume of a sample instance
	e.g. = vol (sample_get_volume inst)

(sample_get_pan)

	Get the pan of a sample instance
	e.g. = pan (sample_get_pan inst)

sample_seek

	Seek to milliseconds position in sample
	e.g. sample_seek inst 1000

sample_destroy

	Destroy a sample
	e.g. sample_destroy sample

Other

(rand)

	random integers between two numbers inclusive
	This uses a Mersenne Twister algorithm
	e.g. = r (rand 0 99)

srand

	Seed the random number generator
	e.g. srand (time)

(time)

	Return time since epoch in seconds
	e.g. = t (time)

print

	print a string (like string_format)
	e.g. print "Hello, I'm % and I like % and %" name like1 like2
	printf-equivalent formating options are available with %(...) for
	example %(3.16g)

(input)

	Read a word from stdin
	e.g. = str (input)

(getenv)

	Get an environment variable
	e.g. = dest (getenv "HOME")

mkdir

	Create a directory
	e.g. mkdir my_string_path

(list_directory)

	List files and directories in a glob
	e.g. explode (list_directory "/home/Pelvis/*") filenames is_dir_flags

(get_system_language)

	Returns the user interface language of the system
	e.g. = lang (get_system_language)
	lang will be in Steam format e.g. "french", "brazilian" etc
	Currently supported are:
		arabic
		bulgarian
		schinese
		tchinese
		czech
		danish
		dutch
		english
		finnish
		french
		german
		greek
		hungarian
		indonesian
		italian
		japanese
		korean
		norwegian
		polish
		portuguese
		brazilian
		romanian
		russian
		spanish
		latam
		swedish
		thai
		turkish
		ukrainian
		vietnamese

(list_drives)

	Get a list of active drive letters in a vector (e.g. "A", "C", ...)
	e.g. = v (list_drives)

(get_full_path)

	Convert a pathname to a fully qualified pathname
	e.g. = filename (get_full_path filename)

(get_args)

	Populate a vector with strings of the command line arguments
	e.g. = v (get_args)

(get_savedgames_path)

	Returns the path to the Saved Games folder
	e.g. = s (get_savedgames_path)

inspect

	print a value in a popup for debugging
	e.g. inspect x

delay

	delay an amount of milliseconds
	e.g. delay 1000

(get_ticks)

	Get milliseconds since BooBoo interpreter launch
	e.g. = ticks (get_ticks)

text_fore

	Change the text foreground colour. See constants for colours.
	Each colour has a bright version toggleable by a boolean.
	e.g. text_fore RED TRUE

text_back

	Change the text background colour. See constants for colours.
	Each colour has a bright version toggleable by a boolean.
	e.g. text_back WHITE FALSE

text_reset

	Reset the text colour
	e.g. text_reset

text_clear

	Clear the screen
	e.g. text_clear

(getch)

	Input a single character from the terminal, not waiting for newline
	e.g. = input_number (getch)

(kbhit)

	Allows non-blocking use of getch. Returns nonzero if a key awaits in the buffer else FALSE.
	e.g. :loop
	e.g. call redraw_ascii_anim
	e.g. ? FALSE (kbhit)
	e.g. je loop
	e.g. = key (getch)
	; Note, while/for loops are considered one instruction, so audio callbacks won't be
	; received unless you use jumps like above (because audio callbacks are called between
	; instructions...) This is referencing callbacks passed to sample_play etc. If you're
	; not using them, audio will play just fine if you use a while loop here.

Constants

VOID is a generic non-constant variable you can use for example to ignore returns values from expression handlers:

	= VOID (sample_play samp)

These are used with text_fore/text_back:

Used with file_seek: